Quarto.yml Document Structure

Comprehensive reference for all configuration options available in the _quarto.yml file

Abstract

A comprehensive reference guide covering all aspects of the _quarto.yml configuration file. This document provides detailed explanations of all configuration sections including project settings, website configuration, format options, metadata, engines, filters, and advanced features. Essential for understanding the full capabilities of Quarto configuration and implementing complex documentation setups.

Keywords

quarto, configuration, yaml, documentation, website, publishing

1 📋 Table of Contents

• 📖 Overview
• 🏗️ Basic Structure
• ⚙️ Project Configuration
• 🌐 Website Configuration
• 📄 Format Configuration
• 🏷️ Metadata Configuration
• 🔧 Engine Configuration
• 🔌 Filters and Extensions
• 🌍 Environment and Variables
• ⚡ Advanced Configuration
• 📋 Complete Example
• ✅ Best Practices
• 🔧 Troubleshooting

2 📖 Overview

The _quarto.yml file is the central configuration file for Quarto projects. It defines how your content is processed, rendered, and published. This document provides a comprehensive reference for all configuration options available in the _quarto.yml file.

3 🏗️ Basic Structure

The _quarto.yml file is written in YAML format and consists of several top-level sections:

# Basic structure
project:
  # Project-level settings

website:
  # Website-specific settings (for website projects)

book:
  # Book-specific settings (for book projects)

format:
  # Output format specifications

metadata:
  # Document metadata

engine:
  # Computational engine settings

filters:
  # Pandoc filters

execute:
    # Code execution settings

4 ⚙️ Project Configuration

The project section defines fundamental project settings.### project.type

Goal: Specifies the type of Quarto project

Options:

• website - Multi-page website
• book - Book with chapters
• manuscript - Academic manuscript
• default - Single document or collection

project:
  type: website

4.1 project.output-dir

Goal: Defines where rendered output files are placed Options: Any valid directory path (relative or absolute)

project:
  output-dir: docs        # For GitHub Pages
  # output-dir: _site     # Alternative
  # output-dir: public    # Alternative

4.2 project.lib-dir

Goal: Specifies location for project libraries and dependencies Options: Directory path for storing project assets

project:
  lib-dir: libs

4.3 project.preview

Goal: Configuration for preview server Options:

project:
  preview:
    port: 4200
    browser: true
    watch-inputs: true
    navigate: true

4.4 project.render

Goal: Controls which files are rendered Options:

project:
  render:
    - "*.qmd"
    - "*.md"
    - "!draft-*.qmd"  # Exclude drafts

5 🌐 Website Configuration

The website section is used when project.type: website.

5.1 website.title

Goal: Sets the main title of the website Options: Any string value

website:
  title: "My Documentation Site"

5.2 website.description

Goal: Provides a description for SEO and metadata Options: String describing the website content

website:
  description: "Comprehensive documentation for my project"

5.3 website.site-url

Goal: Specifies the canonical URL for the website Options: Full URL where the site will be hosted

website:
  site-url: "https://username.github.io/repository"

5.4 website.repo-url

Goal: Links to the source repository Options: URL to the source code repository

website:
  repo-url: "https://github.com/username/repository"
  repo-actions: [edit, issue]

5.5 website.navbar

Goal: Configures the navigation bar Options: Complex structure for navigation elements

website:
  navbar:
    background: primary
    search: true
    logo: "images/logo.png"
    title: "Site Title"
    left:
      - href: index.qmd
        text: Home
      - href: about.qmd
        text: About
      - text: "Documentation"
        menu:
          - href: guide.qmd
            text: User Guide
          - href: reference.qmd
            text: Reference
    right:
      - icon: github
        href: "https://github.com/username/repo"
    tools:
      - icon: github
        menu:
          - text: Source Code
            url: "https://github.com/username/repo"
          - text: Report a Bug
            url: "https://github.com/username/repo/issues"

5.6 website.sidebar

Goal: Configures sidebar navigation Options: Structure for hierarchical navigation

website:
  sidebar:
    style: "docked"        # Options: docked, floating
    search: true
    collapse-level: 2
    contents:
      - href: index.qmd
        text: Home
      - section: "Getting Started"
        contents:
          - href: installation.qmd
            text: Installation
          - href: quickstart.qmd
            text: Quick Start
      - section: "Advanced Topics"
        contents:
          - href: configuration.qmd
          - href: deployment.qmd

5.7 website.page-navigation

Goal: Controls page-level navigation Options: Boolean or detailed configuration

website:
  page-navigation: true
  # Or detailed configuration:
  page-navigation:
    location: bottom
    align: center

5.8 website.footer

Goal: Configures the website footer Options: Text, links, and layout options

website:
  footer:
    left: "Copyright 2025, My Organization"
    right:
      - href: privacy.qmd
        text: Privacy Policy
      - href: terms.qmd
        text: Terms of Use

5.9 website.cookie-consent

Goal: Adds GDPR-compliant cookie consent Options: Configuration for cookie consent banner

website:
  cookie-consent:
    type: express
    style: headline
    palette: dark

5.10 website.google-analytics

Goal: Integrates Google Analytics tracking Options: Google Analytics tracking ID

website:
  google-analytics: "G-XXXXXXXXXX"

6 📄 Format Configuration

The format section defines output formats and their settings.

6.1 HTML Format

Goal: Configures HTML output Options: Extensive customization for web output

format:
  html:
    theme: cosmo                    # Built-in themes
    css: styles.css                 # Custom CSS
    toc: true                       # Table of contents
    toc-depth: 3                    # TOC depth
    toc-location: left              # left, right, body
    number-sections: true           # Number headings
    number-depth: 3                 # Numbering depth
    highlight-style: github         # Code highlighting
    code-fold: true                 # Collapsible code
    code-tools: true                # Code viewing tools
    smooth-scroll: true             # Smooth scrolling
    anchor-sections: true           # Anchor links
    citations-hover: true           # Citation previews
    footnotes-hover: true           # Footnote previews
    fig-width: 8                    # Figure width
    fig-height: 6                   # Figure height
    fig-cap-location: bottom        # Caption location
    tbl-cap-location: top           # Table caption location
    callout-appearance: default     # Callout styling
    page-layout: article            # Page layout
    grid:
      sidebar-width: 250px          # Sidebar width
      body-width: 900px             # Body width
      margin-width: 250px           # Margin width
    mainfont: "Source Sans Pro"     # Main font
    monofont: "Source Code Pro"     # Code font

6.2 PDF Format

Goal: Configures PDF output Options: LaTeX-based PDF generation settings

format:
  pdf:
    documentclass: article          # LaTeX document class
    geometry:
      - top=30mm
      - left=20mm
      - heightrounded
    fontfamily: libertinus          # Font family
    fontsize: 11pt                  # Font size
    linestretch: 1.25               # Line spacing
    number-sections: true           # Number sections
    colorlinks: true                # Colored links
    lot: true                       # List of tables
    lof: true                       # List of figures
    toc: true                       # Table of contents
    toc-depth: 3                    # TOC depth
    bibliography: references.bib    # Bibliography file
    csl: apa.csl                    # Citation style

6.3 Word Format

Goal: Configures Microsoft Word output Options: Word document generation settings

format:
  docx:
    reference-doc: template.docx    # Word template
    number-sections: true           # Number sections
    highlight-style: github         # Code highlighting
    fig-width: 7                    # Figure width
    fig-height: 5                   # Figure height
    toc: true                       # Table of contents
    toc-depth: 3                    # TOC depth

7 🏷️ Metadata Configuration

The metadata section defines document-wide metadata.

7.1 Basic Metadata

Goal: Sets fundamental document information Options: Standard metadata fields

metadata:
  title: "Document Title"
  subtitle: "Document Subtitle"
  author:
    - name: "John Doe"
      email: "john@example.com"
      affiliation: "University Name"
    - name: "Jane Smith"
      email: "jane@example.com"
  date: "2025-01-14"
  abstract: "This document provides..."
  keywords:
    - documentation
    - quarto
    - publishing

7.2 Academic Metadata

Goal: Provides academic publication information Options: Scholarly metadata fields

metadata:
  doi: "10.1000/xyz123"
  arxiv: "2301.12345"
  pmid: "12345678"
  citation:
    type: article-journal
    container-title: "Journal Name"
    volume: 42
    issue: 3
    page: "123-145"
    issn: "1234-5678"

7.3 Custom Metadata

Goal: Allows custom metadata fields Options: Any key-value pairs

metadata:
  custom-field: "custom value"
  project-version: "1.0.0"
  build-date: "2025-01-14"

8 🔧 Engine Configuration

The engine section configures computational engines.

8.1 Jupyter Engine

Goal: Configures Jupyter notebook execution Options: Jupyter-specific settings

engine:
  jupyter:
    kernel: python3
    execute:
      timeout: 300
      allow_errors: false
      error_on_missing_exec: true

8.2 Knitr Engine

Goal: Configures R/Knitr execution Options: R-specific settings

engine:
  knitr:
    opts_chunk:
      echo: true
      warning: false
      message: false
      fig.width: 8
      fig.height: 6

9 🔌 Filters and Extensions

9.1 Pandoc Filters

Goal: Applies document transformations Options: List of filter names or configurations

filters:
  - lightbox                        # Built-in filter
  - custom-filter.py               # Custom filter
  - name: tables
    params:
      style: grid

9.2 Extensions

Goal: Adds functionality through extensions Options: Extension names and configurations

extensions:
  - quarto-ext/fontawesome
  - quarto-ext/lightbox

10 🌍 Environment and Variables

10.1 Environment Variables

Goal: Sets environment variables for rendering Options: Key-value pairs

environment:
  QUARTO_PYTHON: "/usr/bin/python3"
  CUSTOM_VAR: "value"

10.2 Project Variables

Goal: Defines reusable variables Options: Variable definitions

variables:
  github-url: "https://github.com/username/repo"
  version: "1.0.0"
  api-base: "https://api.example.com"

11 ⚡ Advanced Configuration

11.1 Execute Configuration

Goal: Controls code execution behavior Options: Execution parameters

execute:
  enabled: true                     # Enable execution
  cache: true                       # Cache results
  freeze: false                     # Freeze execution
  daemon: false                     # Use daemon
  daemon-restart: false             # Restart daemon
  debug: false                      # Debug mode
  error: false                      # Continue on error
  eval: true                        # Evaluate code
  echo: true                        # Show code
  output: true                      # Show output
  warning: true                     # Show warnings
  include: true                     # Include in output

11.2 Bibliography Configuration

Goal: Manages citations and references Options: Bibliography settings

bibliography: references.bib
csl: chicago-author-date.csl
citation-style: author-year
link-citations: true
citeproc: true

11.3 Cross-Reference Configuration

Goal: Configures cross-referencing Options: Reference settings

crossref:
  fig-title: "Figure"
  tbl-title: "Table"
  eq-title: "Equation"
  sec-title: "Section"
  chapters: true

12 📋 Complete Example

Here’s a comprehensive example showing many configuration options:

project:
  type: website
  output-dir: docs
  preview:
    port: 4200
    browser: true

website:
  title: "My Documentation"
  description: "Comprehensive project documentation"
  site-url: "https://username.github.io/project"
  repo-url: "https://github.com/username/project"
  
  navbar:
    background: primary
    search: true
    left:
      - href: index.qmd
        text: Home
      - text: "Documentation"
        menu:
          - href: guide/index.qmd
            text: User Guide
          - href: reference/index.qmd
            text: API Reference
    right:
      - icon: github
        href: "https://github.com/username/project"
  
  sidebar:
    style: "docked"
    search: true
    contents:
      - href: index.qmd
        text: "Home"
      - section: "Getting Started"
        contents:
          - href: installation.qmd
          - href: quickstart.qmd
      - section: "Advanced"
        contents:
          - href: configuration.qmd
          - href: deployment.qmd
  
  footer:
    left: "� 2025 My Organization"
    right:
      - href: license.qmd
        text: License

format:
  html:
    theme: cosmo
    css: styles.css
    toc: true
    toc-depth: 3
    number-sections: true
    highlight-style: github
    code-fold: true
    code-tools: true
    smooth-scroll: true
    fig-width: 8
    fig-height: 6

metadata:
  author: "Your Name"
  date: last-modified
  version: "1.0.0"

execute:
  cache: true
  freeze: auto

filters:
  - lightbox

bibliography: references.bib
csl: apa.csl

13 ✅ Best Practices

13.1 Organization

1. Group Related Settings: Keep related configuration options together
2. Use Comments: Document complex configurations with YAML comments
3. Consistent Formatting: Maintain consistent indentation and structure
4. Version Control: Track changes to _quarto.yml in version control

13.2 Performance

1. Enable Caching: Use execute.cache: true for computational content
2. Optimize Images: Configure appropriate figure dimensions
3. Selective Rendering: Use project.render to control what gets processed

13.3 Maintenance

1. Regular Updates: Keep up with new Quarto features and options
2. Validate Configuration: Use quarto check to validate your configuration
3. Test Changes: Preview locally before deploying changes

14 🔧 Troubleshooting

14.1 Common Configuration Issues

YAML Syntax Errors: Use proper indentation and quotes when needed

2. Invalid Paths: Ensure all file paths are correct and accessible
3. Missing Dependencies: Install required themes, filters, or extensions
4. Execution Errors: Check engine configuration and code execution settings

14.2 Validation

# Check configuration
quarto check

# Preview with verbose output
quarto preview --verbose

# Render with debug information
quarto render --debug

14.3 Debug Configuration

execute:
  debug: true

project:
  preview:
    watch-inputs: true

This comprehensive reference covers all major aspects of the _quarto.yml configuration file. Use it as a guide to customize your Quarto projects according to your specific needs and requirements.